Alterner les créations publicitaires avec l'API Select URL

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Utilisez l'API Select URL pour tirer parti de Shared Storage afin de déterminer la création qu'un utilisateur voit sur différents sites.

Un annonceur ou un producteur de contenu peut souhaiter appliquer différentes stratégies de rotation de contenu à une campagne, et faire tourner les contenus ou les créations pour en améliorer l'efficacité. L'API Select URL permet d'exécuter différentes stratégies de rotation, telles que la rotation séquentielle et la rotation répartie uniformément, sur différents sites.

Avec la rotation des créations de l'API Select URL, vous pouvez stocker des données telles que l'ID de la création, le nombre de vues et les interactions des utilisateurs pour déterminer les créations que les utilisateurs voient sur différents sites.

Pour en savoir plus sur l'API sous-jacente et le fonctionnement de la sélection, consultez la documentation de l'API Select URL.

Essayer la rotation des créations

Pour tester la rotation des créations, assurez-vous que l'API Select URL et Shared Storage sont activées:

• Dans chrome://settings/content/siteData, sélectionnez Allow sites to save data on your device ou Delete data sites have saved to your device when you close all windows.
• Dans chrome://settings/adPrivacy/sites, sélectionnez Site-suggested ads.

Pour obtenir une version en direct des exemples de code de ce document, essayez notre démo en direct de Shared Storage.

Démonstration avec des exemples de code

Dans cet exemple :

• creative-rotation.js est le script tiers qui définit le contenu à faire pivoter, ainsi que les données qui déterminent le contenu suivant à sélectionner et à afficher, comme les poids dans cet exemple. La page de l'éditeur exécute ce script. Ce script appelle le worklet Shared Storage pour déterminer le contenu à afficher en fonction des données disponibles dans l'espace de stockage et de la liste des URL à sélectionner.

• creative-rotation-worklet.js est le worklet de stockage partagé du tiers qui recherche la stratégie de rotation, calcule le contenu à publier ensuite et renvoie ce contenu.

Fonctionnement de la démonstration

1. Lorsqu'un utilisateur accède à la page de l'éditeur, celle-ci charge le script creative-rotation.js du tiers. Le script de rotation des créations est chargé de charger et d'exécuter le worklet de stockage partagé. Le script fournit à l'appel du worklet une liste d'URL à sélectionner.
2. Dans le worklet, si l'espace de stockage partagé n'a pas encore été initialisé, il est initialisé avec la stratégie de rotation des créations et l'indice de création initiaux. La stratégie de rotation initiale utilisée dans cette démonstration est la stratégie séquentielle.
3. Le worklet lit le mode de rotation à partir du stockage partagé et renvoie l'index de l'annonce suivante. Dans le cas du mode de rotation séquentielle, il met également à jour l'index de la création dans l'espace de stockage partagé avec la nouvelle valeur à utiliser pour l'appel suivant.Le worklet renvoie un objet URN FencedFrameConfig ou opaque en fonction de la valeur resolveToConfig utilisée lors de l'appel de selectURL.
4. Le script de rotation des créations affiche l'annonce sélectionnée dans un cadre clôturé ou un iFrame. Pour en savoir plus sur les types de retour, consultez le document Afficher une annonce.
5. Lorsqu'un utilisateur modifie le mode de rotation, le worklet Shared Storage met à jour la valeur du mode de rotation de la création stockée dans Shared Storage.
6. Lorsque vous actualisez la page de l'éditeur, les étapes 1 à 4 sont répétées, ce qui permet de sélectionner l'annonce suivante à afficher en fonction de la stratégie de rotation sélectionnée.

Exemples de code

Vous trouverez ci-dessous les exemples de code pour creative-rotation.js et creative-rotation-worklet.js.

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

Tutoriel avec captures d'écran

1. Pour accéder à la rotation des créations à l'aide de l'API Select URL et de Shared Storage, accédez à https://shared-storage-demo.web.app/. Choisissez la démonstration "Rotation des créations".

2. Choisissez d 'explorer la démonstration en tant qu'éditeur A. Vous serez redirigé vers la page https://shared-storage-demo-publisher-a.web.app/creative-rotation. La page charge du contenu numéroté en fonction des données de rotation des créations enregistrées dans Shared Storage, auxquelles vous accédez via l'API Select URL. Les modes de démonstration de la rotation des créations sont la rotation séquentielle, la distribution régulière et la distribution pondérée. Le worklet exécute la logique pour sélectionner le contenu qui s'affiche dans l'iFrame. L'image suivante montre la page de l'éditeur.

   
   

3. Pour afficher ce qui est stocké dans Shared Storage, accédez à Application -> Shared Storage dans les outils de développement Chrome. Deux entrées sont créées pour l'espace de stockage partagé. Un espace de stockage vide est disponible pour l'origine https://shared-storage-demo-publisher-a.web.app. Il contiendra un espace de stockage spécifique à cette origine et restera vide pour notre démonstration, car l'éditeur n'a pas besoin d'écrire dans l'espace de stockage partagé. Notez qu'un espace de stockage similaire sera créé pour l'éditeur B lorsque vous accéderez à cette page ultérieurement pour la démonstration.

   
   

4. Une autre entrée Shared Storage sera créée pour l'origine https://shared-storage-demo-content-producer.web.app. Il s'agit du stockage de l'iFrame tiers intégré sur la page de l'éditeur. Ce stockage permettra de partager des données entre les deux éditeurs disponibles afin de coordonner la sélection des créations. Ce stockage partagé permettra d'enregistrer des informations sur la création diffusée et la stratégie de rotation en enregistrant deux paires clé-valeur. La première clé utilisée dans la démonstration est creative-rotation-index, dont la valeur correspond à l'index de la création actuel en mode séquentiel. La deuxième clé est creative-rotation-mode, qui dicte la stratégie de rotation utilisée.

   
   

5. Si vous actualisez la page en mode séquentiel, la création suivante de la séquence 1, 2, 3, 1, etc. s'affiche. La valeur de la clé creative-rotation-index change en fonction de l'index de la création affichée en mode séquentiel.

   
   

6. Si vous modifiez le mode de rotation des créations à l'aide des boutons de contrôle, la valeur de la clé "creative-rotation-mode" sera mise à jour dans la stratégie correspondante. Le code du worklet l'utilisera pour choisir la prochaine création à afficher dans l'iFrame. Notez que la valeur enregistrée pour "creative-rotation-index" ne change pas pour les modes de rotation autres que séquentiels.

   
   

7. Accédez à la page de l'éditeur B sur https://shared-storage-demo-publisher-b.web.app/creative-rotation. En mode séquentiel, la création affichée doit être la suivante dans la séquence affichée lorsque vous accédez à l'URL de l'éditeur A. En inspectant l'espace de stockage partagé du producteur de contenu, vous constatez que "Éditeur A" et "Éditeur B" partagent le même espace de stockage et utilisent les paramètres qui s'y trouvent pour sélectionner la prochaine création à diffuser et la stratégie de rotation à utiliser.

   
   

8. Le stockage partagé de "Éditeur B" est vide, comme celui d'"Éditeur A".

   
   

   Cas d'utilisation

   Vous trouverez dans cette section tous les cas d'utilisation disponibles pour l'API Select URL. Nous continuerons d'ajouter des exemples à mesure que nous recevrons des commentaires et découvrirons de nouveaux cas de test.

   • Faites tourner les créations publicitaires: stockez des données telles que l'ID de la création et l'interaction de l'utilisateur pour déterminer les créations que les utilisateurs voient sur différents sites.
   • Sélectionner des créations publicitaires par fréquence: utilisez les données sur le nombre de vues pour déterminer les créations que les utilisateurs voient sur différents sites.
   • Exécuter des tests A/B: vous pouvez attribuer un utilisateur à un groupe de test, puis stocker ce groupe dans Shared Storage pour y accéder sur plusieurs sites.
   • Personnaliser l'expérience pour les clients connus: partagez du contenu personnalisé et des incitations à l'action en fonction de l'état d'enregistrement ou d'autres états de l'utilisateur.

Interagir et envoyer des commentaires

Notez que la proposition d'API Select URL est en cours de discussion et de développement, et est susceptible de changer.

Nous aimerions connaître votre avis sur l'API Select URL.

• Proposition: consultez la proposition détaillée.
• Discussion: rejoignez la discussion en cours pour poser des questions et partager vos insights.

Se tenir informé

• Liste de diffusion: abonnez-vous à notre liste de diffusion pour recevoir les dernières informations et annonces concernant les API Select URL et Shared Storage.

Besoin d'aide ?

• Assistance pour les développeurs: échangez avec d'autres développeurs et obtenez des réponses à vos questions dans le dépôt d'assistance pour les développeurs de la Privacy Sandbox.